request.py 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. from __future__ import absolute_import
  2. from .filepost import encode_multipart_formdata
  3. from .packages.six.moves.urllib.parse import urlencode
  4. __all__ = ["RequestMethods"]
  5. class RequestMethods(object):
  6. """
  7. Convenience mixin for classes who implement a :meth:`urlopen` method, such
  8. as :class:`~urllib3.connectionpool.HTTPConnectionPool` and
  9. :class:`~urllib3.poolmanager.PoolManager`.
  10. Provides behavior for making common types of HTTP request methods and
  11. decides which type of request field encoding to use.
  12. Specifically,
  13. :meth:`.request_encode_url` is for sending requests whose fields are
  14. encoded in the URL (such as GET, HEAD, DELETE).
  15. :meth:`.request_encode_body` is for sending requests whose fields are
  16. encoded in the *body* of the request using multipart or www-form-urlencoded
  17. (such as for POST, PUT, PATCH).
  18. :meth:`.request` is for making any kind of request, it will look up the
  19. appropriate encoding format and use one of the above two methods to make
  20. the request.
  21. Initializer parameters:
  22. :param headers:
  23. Headers to include with all requests, unless other headers are given
  24. explicitly.
  25. """
  26. _encode_url_methods = {"DELETE", "GET", "HEAD", "OPTIONS"}
  27. def __init__(self, headers=None):
  28. self.headers = headers or {}
  29. def urlopen(
  30. self,
  31. method,
  32. url,
  33. body=None,
  34. headers=None,
  35. encode_multipart=True,
  36. multipart_boundary=None,
  37. **kw
  38. ): # Abstract
  39. raise NotImplementedError(
  40. "Classes extending RequestMethods must implement "
  41. "their own ``urlopen`` method."
  42. )
  43. def request(self, method, url, fields=None, headers=None, **urlopen_kw):
  44. """
  45. Make a request using :meth:`urlopen` with the appropriate encoding of
  46. ``fields`` based on the ``method`` used.
  47. This is a convenience method that requires the least amount of manual
  48. effort. It can be used in most situations, while still having the
  49. option to drop down to more specific methods when necessary, such as
  50. :meth:`request_encode_url`, :meth:`request_encode_body`,
  51. or even the lowest level :meth:`urlopen`.
  52. """
  53. method = method.upper()
  54. urlopen_kw["request_url"] = url
  55. if method in self._encode_url_methods:
  56. return self.request_encode_url(
  57. method, url, fields=fields, headers=headers, **urlopen_kw
  58. )
  59. else:
  60. return self.request_encode_body(
  61. method, url, fields=fields, headers=headers, **urlopen_kw
  62. )
  63. def request_encode_url(self, method, url, fields=None, headers=None, **urlopen_kw):
  64. """
  65. Make a request using :meth:`urlopen` with the ``fields`` encoded in
  66. the url. This is useful for request methods like GET, HEAD, DELETE, etc.
  67. """
  68. if headers is None:
  69. headers = self.headers
  70. extra_kw = {"headers": headers}
  71. extra_kw.update(urlopen_kw)
  72. if fields:
  73. url += "?" + urlencode(fields)
  74. return self.urlopen(method, url, **extra_kw)
  75. def request_encode_body(
  76. self,
  77. method,
  78. url,
  79. fields=None,
  80. headers=None,
  81. encode_multipart=True,
  82. multipart_boundary=None,
  83. **urlopen_kw
  84. ):
  85. """
  86. Make a request using :meth:`urlopen` with the ``fields`` encoded in
  87. the body. This is useful for request methods like POST, PUT, PATCH, etc.
  88. When ``encode_multipart=True`` (default), then
  89. :meth:`urllib3.filepost.encode_multipart_formdata` is used to encode
  90. the payload with the appropriate content type. Otherwise
  91. :meth:`urllib.urlencode` is used with the
  92. 'application/x-www-form-urlencoded' content type.
  93. Multipart encoding must be used when posting files, and it's reasonably
  94. safe to use it in other times too. However, it may break request
  95. signing, such as with OAuth.
  96. Supports an optional ``fields`` parameter of key/value strings AND
  97. key/filetuple. A filetuple is a (filename, data, MIME type) tuple where
  98. the MIME type is optional. For example::
  99. fields = {
  100. 'foo': 'bar',
  101. 'fakefile': ('foofile.txt', 'contents of foofile'),
  102. 'realfile': ('barfile.txt', open('realfile').read()),
  103. 'typedfile': ('bazfile.bin', open('bazfile').read(),
  104. 'image/jpeg'),
  105. 'nonamefile': 'contents of nonamefile field',
  106. }
  107. When uploading a file, providing a filename (the first parameter of the
  108. tuple) is optional but recommended to best mimic behavior of browsers.
  109. Note that if ``headers`` are supplied, the 'Content-Type' header will
  110. be overwritten because it depends on the dynamic random boundary string
  111. which is used to compose the body of the request. The random boundary
  112. string can be explicitly set with the ``multipart_boundary`` parameter.
  113. """
  114. if headers is None:
  115. headers = self.headers
  116. extra_kw = {"headers": {}}
  117. if fields:
  118. if "body" in urlopen_kw:
  119. raise TypeError(
  120. "request got values for both 'fields' and 'body', can only specify one."
  121. )
  122. if encode_multipart:
  123. body, content_type = encode_multipart_formdata(
  124. fields, boundary=multipart_boundary
  125. )
  126. else:
  127. body, content_type = (
  128. urlencode(fields),
  129. "application/x-www-form-urlencoded",
  130. )
  131. extra_kw["body"] = body
  132. extra_kw["headers"] = {"Content-Type": content_type}
  133. extra_kw["headers"].update(headers)
  134. extra_kw.update(urlopen_kw)
  135. return self.urlopen(method, url, **extra_kw)